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ODO NOUS SHSESEUWWYW 


GENERAL INFORMATION 


CP/A is a general purpose command control program for the OSS disk 
operating system. The CP/A user has two types of commands available 
intrinsic commands and extrinsic commands. The intrinsic commands 
are those commands which are executed directly via CP/A code 
Extrinsic commands are executed by loading and running a program 


The following commands are CP/A intrinsic 


DIRECTORY List directory 

SAVE Save a program 

LOAD Load a program 

RUN Run @ program already in RAM 

ERASE Erase a file from it’s medium 

PROTECT Protect a file from erasure 
or change 

UNPROTECT Unprotect a protected file 

RENAME Rename a file 


The CP/A examines the first three characters of the user input for 

a match with the intrinsic commands. If the first three characters 
match, the remaining contiguous characters through a blank ($20), 

carriage return ($0D) or a comma are ignored. Thus DIR, DIRECTORY 

DIRGLOP, etc all access the DIRECTORY intrinsic command 


The CP/A, upon determining a command is not intrinsic, will attempt 
to execute an extrinsic command. The user command is converted into 
a filespec of the form: 


Device: command. COM 
\ 
The device is a single character device specifier (usually A or B). 
If the user does not specify a device, then the default device is 
used. The .COM is always appended to the command. The command 
BASIC will generate a filespec of 


4: BASIC. COM 


CP/A will next attempt to open and load a file with the generated 
filespec. If the file load is properly terminated, CP/A will transfer 
to the loaded program’s start location. The user loaded program now 
has control of the system 


DEFAULT DEVICE 


CP/A starts execution with a default device of "A:" which is disk 
drive 1. The user may change the default drive by entering the 
new drive spec (ie "B:") followed by a carriage return. CP/A uses 
the default drive as the input line prompt character in the form: 
Alt 


The default device is used by CP/A in all cases where it constructs 
a filename from user input and the user has not specified a device 
The command 

LOAD BASIC. COM 


will load A: BASIC. COM assuming the default drive is "A:". The 
command 


LOAD B: BASIC. COM 


will load B:BASIC.COM no matter what the default drive is 


COMMAND DETAILS 


For each command, the command syntax is followed by an example of 
actual usage and a decription of the command’s operation 


SAVE 


LOAD 


RUN 


SAVCE] filespec start—-hex-adr end-hex-adr 


SAVE TEST BOO BOO 


A file will be created with the name "filespec” and will contain 
€1l data from “start-hex-adr" up to, but not including 


“end-hex-adr". CP/A will write a four byte save file header 
before the data. The first two bytes are "start—-hex-adr" 
and the second two bytes are "end-hex-adr”. This four byte 


header is compatible with the OSS Assembler object output 


LOALCD] filespec 


LOAD TEST 


The specified file will be loaded. The files first four bytes 
are used to determine the load start address and end address 
The start address must be less than the end address. The file 
load start address is placed into the OSS go-location (3F9) 


RUN optional—-hex-adr 
RUN $800 


CP/A will branch to the run address. The address is either the 
specified hex address or, if unspecified, the address at the 
go-location. The address at the go-location is set by 

system initialization (to CP/A), the act of LOADing a program, 
or by an application program that has called CP/A. BASIC and 
the ASSEMBLER both set the go-location at their respective 
warmstart entry points 


DIRECTORY 


DIRCECTORYI optional-filespec 
DIR *. COM 


The CP/A will open the specified "device: filespec" for directory 
listing. If the user does not specify a filespec, the default 


default-device: *.* 


filespec will be used 


ERASE 
ERACSEIJ filespec 
ERASE TEST. * 
The specified file or files will be erased from the device 
provided that they are not protected 
PROTECT 
PROCTECT) filespec 
PRO BASIC. COM 
The specified file or files, are protected from modification 
erasure or renaming. 
r 
UNPROTECT 
UNPCROTECTI filespec 
UNP DATA. TST 
The specified file or files, are unprotected. They may 
now be erased, modified, or renamed 
RENAME 
RENCAMEJ old-filespec new-filespec 
REN GLOP ACTS. NEW 


The files matching the old-filespec are renamed according to 
the new-filespec 


INIT 


(Extrinsic command) 


INIT (no parameters) 


The INIT command is used to physically and logically initilize 
an OSS format diskette. A diskette can be used by the OSS 
system (version 1) if and only if it has been initialized by 
INIT. Initializing a diskette destroys all] previous information 
on the diskette 


The INIT program (INIT. COM) begins by requesting the INIT 
function to be performed. These functions are 


1) INIT a disk with boot record 

2) INIT a disk without boot record 
3) Re-write the boot record. 

4) Return to CP/A 


The first two functions physically and logically initialize the 
working surface of the disk. If a disk is initialized without 
a boot record, the disk will contain 719 sectors of 128 bytes 
each; however, the diskette is not bootable. If the disk is 
initialized with a boot record, the disk will contain 680 
sectors of 128 bytes each and a 6.5K boot record. The boot 
Tecord contains the operating system located from page %AS 
thru page SBF plus two additional pages of boot loader code 
The third function is used to re-write the operating system 

to the boot record. The OSS disk must have been previously 
formatted using function 1 to execute function 3. 


The OSS File Manager (Version 1) uses 9 sectors for file 
management information. The INIT program also logically 
formats these 9 sectors. (See OSS DFM document. ) 


DUPDSK (Extrinsic Command) 


DUPDSK (no parameters) 


The DUPDSK command is used to make a duplicate copy of one OSS 
disk on to another OSS disk. Both disks must be initialized 
in the same wayi they both must either have or not have a boot 
record. The boot record is not copied by DUPDSK 


COPY 


(Extrinsic Command) 


cOPY from—filespec to-filespec 
COPY A: BASIC. COM B: BASIC. COM 


The from-file is copied to the to-file. The to-file does not 
have to be a disk file, but may be any device. , The from-file 
is unmodified. The from-filespec need not be a disk file, but 
it must provide an EOF to terminate the copy 


USER WRITTEN EXTRINSIC COMMANDS 


Any user file of the name “name. COM" may be used as a CP/A extrinsic 
command. The program may be placed at any memory location that does 
not interface with other concurrent programs. The program entry 
point will be at the address of the first byte SAVEd 


The ASCII command line that was entered to invoke the extrinsic 
command is placed by CP/A at location $280. The executing extrinsic 
program can examine this (unmodified) command line for parameters it 
may require. The current default device value is located at %BCFE 
in version 1 of the OSS system. CP/A will yump to the extrinsic 
command with IOCB numbers 1 through 7 closed. IOCB number O is open 
for the current console device for both input and output. 10cB 
number O should not be opened or closed by the command code (unless 
that is the purpose of the command). The normal command exit is to 
CP/A at location $BFFD 
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GENERAL INFORMATION 


The OSS Operating System provides the user with a uniform 1/0 
interface to the various system I/O devices. The user places 1/0 
command information in one of eight system I/O control blocks 
(IOCBs) and calls the OS entry point (OS in system memory map) 

The OS interperts the command and calls upon a Device Handler to 
perform the requested I/0 operation. OS device handlers are coded 
in a specific format that provides a uniform interface to the OS 


The OS uses a file specifier to determine the device handler that 
is to be used for the 1/0 operation. The file specifier is an 
ASCII string of the format 


DN: filename 


D - Device character code that indentifies that 
device handler in the device table. The D 
may be any ASCII value. 


N - Optional sub device specifier. The N if 
specified, must be an ASCII 0-9. The OS 
will supply a default value of 1. 


filename - Optional filename. If the device handler 
Tequires a filename, it must directly follow 
the required colon. The filename format is 
set by the requirements of the device 
handler 


-1- 


10CBs 


There are Eight IOCBs in the system. The first I0CB (IOCB #0) is 
located at address IOCB (see memory map). Each IOCB is 16 bytes 
in length and all IO0CBs are contiguous. The following details 
the specific use of each IOCB byte 


FIELD DISPL LENGTH 


DHID ° 1 Device Handler Index. Set by 
OS. DHID is $FF if IOCB 
not open. 

DVCNO 1 1 Device Handler sub-device 


number. The binary value 
($00-$09) of the N in the 
file specifer. (Default 
= 1). 


OscomM 2 1 Operating System command 
The command OS is to execute 


IOSTAT 3 1 1/0 operation status. In 
general, values greater 
than or equal to 128 ($80) 
are errors 


BUFADR 4 2 User buffer adr in the 
normal 6502 low/high order 
Points to File Specifer (when 
Tequired), or to user data 
buffer. A 

4 

PUTADR 6 2 The address (minus one) of the 
DH put routine. The user may 
call the DH put routine directly 
using this vector 


BUFLEN 8 2 User buffer length in the normal 
6502 low/high order. If BUFADR 
points to File Specifier, then 
BUFLEN is not required 


AUX1 10 1 Auxillary Byte 1. This byte is 
used to contain the open type 
code while the IOCB is open 


AUX2 11 1 Auxillary bytes 2-6 used as 
AUX3 12 1 required by individual Device 
AUX4 13 1 Handlers 

AUX5S 14 1 

AUXS 15 1 


OS COMMANDS 


The OS commands 


1) OPEN 


2) DATA 


fall into three general classes 


and CLOSE 


The user specifed IOCB is opened for use with the 
device specified by the File Specifier 


The specified IOCB must not be currently opened. The 
OS will determine the requested device handler from 

the file specifier and will place the device handler 
index in the IOCB The device handler open routine will 
be called to provide whatever device open functions are 
required. Once the IOCB has been properly opened, it 
may be used for data I/0 and Device Dependent commands 


When the user has finished with the Device, the IOCB 
should be closed via the OS CLOSE command. 


1/0 

The OS performs I/0 operations to and from a user record 
buffer. The user supplies the OS with the address of a 
buffer and a data buffer length. There are five types 
of DATA 1/0 commands. These commands will be detailed 
later in this document 


3) DEVICE DEPENDENT COMMANDS 


Device Dependent Commands are those commands that are 
not universal to all devices, but are specific to a 
particular device. The OS interperts all commands 
above a certain value to be Device Dependent Commands 
If the IOCB used, has not been opened, OS assumes that 
@ filespec is present and acts upon it in the same 
manner as openi (except the DH open routine is not 
called and the IOCB is "open" for the one command only) 


The following list details the OS commands and the data required for 


each command. 
COMMAND 


OPEN 


GETRECORD 


VALUE (HEX) DESCRIPTION 


$01 Open a device for I/0. The address 
of the filespec is pointed to by 
BUFADR. AUX1 must have 04 bit on 
if input, OB bit on for output, or 
both 04 and O08 bits on if device 
is to used for input and output 
AUX1 may have other bits set on for 
special device handler OPEN 
functions 


$04 A record of length BUFLEN will be 
moved into the buffer pointed to 
by BUFADR. The IOCB must have been 
OPENed for input. 


GETLINE 


PUTRECORD 


PUTLINE 


CLOSE 


STATUS 


DEVICE 
DEPENDENT 


$05 


$08 


$09 


$0C 


$0OD 


$OE-$7F 


A line of ASCII input terminated by 

@ carriage return (0D) will be 
placed in a buffer pointed to by 
BUFADR. The BUFLEN field determines 
the maximum line size. The IOCB must 
have been OPENed for input 


A record of length BUFLEN will be 
sent to the device from the buffer 
pointed to by BUFADR. The IOCB 
must have been OPENed for output 


A line of ASCII input terminated by 
@ carriage return ($0D) will be 
sent to the device from the buffer 
pointed to by BUFADR. The IOCB 
must have been OPENed for output 


The IOCB and file are closed 


The device will return a status byte 
in the IOSTAT field. The status 
returned is Device Dependent. The 
IOCB need not have been OPENed. If 
not OPEN, BUFADR must point to a file 
specification 


The DEVICE DEPENDENT commands are sent 
directly to the device handler. The 
IOCB need not have been OPENed. If 
not OPEN, BUFADR must point to a file 
specification. (The OSS Disk File 
Manager supports commands %20-$26; 

see the OSS DFM documentation for 
details. ) 


OS STATUS 


All OS operations return a status value in the IOSTAT field. OS conventior 
is that status values of $80 or greater indicate some sort of error 


VALUE (HEX) MEANING 
$01 No error or warning 
$02 Truncated ASCII line. The OS did not find 


a $0D within BUFLEN for ASCII line 1/0 


$03 End of file look ahead. The last byte 
transfered from the DH was its end-of-file 
byte. The DH must set this status 


$80 Operation aborted. Set by Device Handler 

$81 Device not ready. Set by Device Handler 

$82 Device does not exist. The device was not 
found is the OS device table 

$83 Data Error. Set by Device Handler 

$84 Invalid Command. The Device Handler has 
rejected the command 

$85 Device/File not open. The IOCB has not 
been OPENed for the operation 

$86 The IOCB specified is invalid. 

$87 The device is write protected 


Various Device Handlers may set other values as required 


USING THE OS from ASSEMBLY LANGUAGE 


Once the user has set up an IOCB with the required information, the X- 
register is loaded with the IOCB number (0-7) times 16 and the OS is 
called at the OS entry point (see memory map). The OS will return to 
the user with X register unmodified, the Y register will contain the 
status value, and the accumulator value is unpredictable. The following 
is an example 


LDXx #$50 + USING IOCB #5 

JSR os 3; CALL OS 

TYA ; SET PROCESSOR STATUS FLAG 
BMI ERROR 3 BRANCH IF ERROR 

BPL ¢ooDIO ; ELSE 1/0 WAS GOOD 


DEVICE HANDLERS 


A user may create a Device Handler for any required purpose. The user 
Need only code the DH according to the OS conventions and make a unique 
entry for the device in the OS device table 


The Device Handler table contains eight possible entries. The OSs 
system as shipped uses four of the entries, the remaining four are 
avaiable to the user. The format of a Device Handler table entry is as 
follows. 


FIELD LENGTH DESCRIPTION 


DNAME 1 Device Name. Usually an ASCII 
value. OS uses A, B, E, and P 
A zero DNAME indicates an 
unused entry 


DHVTA 2 Device Handler Vector Table 
Address. The address of the DH 
vector table in normal 6502 
low/high fashion 


The Device Handler Vector Table contains six consecutive address 
(normal 6502 type) that point to the routines in the DH that 
perform the indicated functions 


1) Open Device 

2) Get Device Status 

3) Get Data Byte i 
4) Put Data Byte id 
5) Close Device 

6) Device Dependent Command 


The OS will call one of the six Device Handler functions directly via 
DHVT. Upon entry to the DH function the X register will contain the 
IOCB number (0-7) times 16. The user may use the register to directly 
access the specified IOCB via the abs,X instructions. When the Put 
Data Byte function is called, the accumulator will contain the data 
byte. The Device Handler must return a status value to OS in the 

Y register. If the Get Byte function is called, the data will be 
returned in the accumulator 


The zero page locations DHZPG through DHZPGE (see memory map) are 
available for use by device handlers as temporary storage. These 
locations are subject to change upon exiting from the DH code 


DEVICE E: 


The device E: (EDITOR) is @ device handler which interfaces to the 
Apple Monitor "getline" and "putline" routines. The E: device 
handler provides the user with all the line editing features 

provided by whatever Apple Monitor prom the user has installed 

All E: 1/0 is accomplished through the output vector routine at 

$36 and the input vector routine at $38. The vectors are initialized 
by OSS to use the Apple Keyboard and CRT screen 


IOCB #0 is used by OSS as the system console and is opened using 
device E: upon system initialzation. All OSS system programs 
(CP/A, BASIC, DMGR, etc) use IOCB #0 for console 1/0. No OSS 
system routine closes IOCB #0. 


The user may change the console device from the Apple keyboard 
and screen. There are two ways of accomplishing this. The 
vectors at $36 and/or $38 may be modified, or IOCB #0 may be 
closed and reopened to another device. The first method will 
Tetain the Apple monitor line edit features such as backspace 
and line delete. The second method will provide line editing 
if and only if the device handler used provides for line 
editing. 


See Appendix A for listing of Device E: routine 


DEVICE Pn: 


The device Pn: (PORT n) is a device handler for the eight Apple 
slots. The “n" specifies which port is to be used (0-7) 


When a port is OPENed the device address (C100,C200 etc) of the 
port is stored in the IOCB. When a Pn: data byte 1/0 is called 
for, the following sequence occurs 


1) The device address saved in the IOCB are 
swapped with the vectors at $36 and $38 


2) If the function is PUTBYTE, the most 
significant bit ($80) of the data byte 
is inverted and the byte is output through 
location $36. If the function is GETBYTE 
the data byte is obtained through location 
$38. The received data byte’s most significant 
bit ($80) will be inverted by th Pn: device 
handler 


3) The device address at $36 and $38 will be 
swapped with the device address in the IOCB 


The sequence of operations of Pn: allow the user to open several 
ports simultaneously and perform 1/0 through them as required 

The inversion of the data byte’s most significant bit is required 
because all OSS software is ASCII based 


See Appendix A for listing of Device P: routine 


SYSTEM MEMORY MAP 


LOCATION 


BFFD 
BFFA 
BFF8 
BFF& 
BFFS 
BDAO 
BD87 
BD8O 
BDOO 
BCFE 
B900 
B850 
ADAO 
ADA1 
ADA2 
ABOO 
A800 
0800 
0400 
O3F9 
O3FO 
0280 
0200 
0100 
0080 
OO7F 
0079 
0068 
0050 
0020 
0000 


LABEL 


CPRTN 
SINIT 
HIMEM 
LOMEM 
OSVER 
OSENT 
DHTAB 
DIOB 
10CB 
DEFDRV 
CPAENT 


DFMNUMF 
DFMDIR 
DFMBUF 
DIOENT 


CMDLINE 


DHZPGE 
DHZPG 


(Version 1.0) 


USAGE 


JMP CP/A 

JUMP system initilizer 

HIMEM 

LOMEM 

OSS version number 

OS entry address 

Device table (8 devices) 

Disk I/0 Block 

IOCBs (8 IOCBs) 

Default Drive (ASCII character) 
CP/A entry address 

E: and P: device handlers 
Number of file buffers (4 default) 
File buffer allocation direction ($80) 
File buffers start address (#ABOO) 
Disk I/0 Routine 

File buffers 

User Ram 

Apple screen buffer 

JMP go-location 

Auto start Rom vectors 

CP/A command line 

Line buffer and work space 

6502 stack 

Application zero page Ram 

Top of Device Handlers temps 
Start of Device Handlers temps 
OSS system zeros page 

Available zero page 

Apple Monitor Ram 

Available zero page 


APPENDIX A 
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PAGE 23 SHEP OSS OP SYS AND FMS 
—-PORT DEVICE HANDLER ———- —-_—_— —- ———— = 


PAGE “PORT DEVICE HANDLER’ 

580 ne i omar nt ETFs oe zs = = 
581 i APPLE PORT DEVICE 
582 i 

_..--- $83 .—__— -007C -.-PDHCHR -EQU .-_AEDCHAR —______+—_DATA-CHAR —_____.---— 
584 007A PDHICD EQU DHZPG+1 s IOCB DISPL 
565 007B PDHFLG EQU DHZPG+2 i 1/0 FLAG 

—....-$86 ——_BFFD -- ORG — —-$B8850 _——$ 
587 3 
588 Bs850 PORTDH EQU * 

_..._5B9 BS50 5CBS —__——_—__-_—_DB @EPDHOPN - +—OPEN —-— 
590 BeS2 CS5BS DB @@AEDSTA 3 STATUS 
591 BB54 79B8 DB @@PDHGBT + GET BYTE 
592 B854 73BS —- DB -—___@@PDHP BT ________+_PUT_BYTE—_____— — 
593 BB58 CSBS DB @@AEDSTA + CLOSE 
594 B85A C5BB DB @@AEDSTA i DEVICE DEPENDENT 
59S + — 
596 BS5sC PDHOPN EQU * + OPEN PORT N 
597 B85C A900 LDA #0 i SET ZERO TO 

_ 598. BS5E SDOFBD —____ STA ___ICAUX6, X______+ LOW-ADDR BYTE OUT —— 
599 BeS1 FDODBD STA ICAUX4, X i; LOW ADDR BYTE IN 
600 ; 

—___—_601-B864 BDO1BD LDA AICDNO, x +—CET_DEVICE NO — 
602 BB67 2907 AND #507 i; ISOLATE 3 LSB 
603 B69 0900 ORA #$CO s+ OR IN ADR HI 

—-604_BE4B -9DOEBD STA TCAUKS & +—_ HI GH-ADDR-BY¥FE—OUT—_—___—- 

605 B@6E 9DOCBD STA ICAUX3, X 3 HIGH ADDR BYTE IN 
606 B871 DOS2 BNE AEDSTA + DONE 
407_. + 7 = 
608 B873 PDHPBT EQU * ‘; PUT DATA BYTE 
609 B873 857C STA PDHCHR 3 SAVE DATA BYTE 

—.—610 B875-A900 LDA | #0 +—INDIGATE—OUT RUT 
611 B877 Foo2 BEG PDHGP 
612 ; 

- 613 -—_B879 PDHCBT—Eav- mel ad 
614 B879 AIFF LDA #$FF 3 INDICATE INPUT 
615 i 
616 8873 RDHCP —EQU * ~ 
617 B87B 857B STA PDHFLG i SAVE FLAG 
618 B87D BA TXA 

—_—619 B87E AS TAY +—1068-DI-SPL—48—-¥——___— 
620 B87F A203 LDX #3 ; SAVE X FOR 4 BYTE MOVE 
621 3 
o22 B681-B536 PDHM i 4+-DA — $36, X- - 3+—CET—APPLE—SHWIFEH BYTE —— 
623 BBS3 48 PHA i+ SAVE ON STACK 
624 BE84 BIOCBD LDA ICAUX3, Y i MOVE VECTOR FROM IOCB 
25-BE87-9536 - STA $36,% —+—F8-APPLE-SWIFGH BYTE ——— 
626 BBB9 CB INY 
627 BBBA CA DEX r 

———-628 BESB10F4 BPL PDH —+— BRI F—-MORE—F-8 OVE 

( 629 3 
630 B&SD 8474 STY PDHICD 3 SAVE IOCB DISPL 

———631 BS8F 204688 wR PDHCO —_—i+—68-b8 1+-o-—_—_—__—_—— 


632 BA92 857C STA PDHCHR i SAVE POSSIBLE INPUT CHAR 
633 3 : 


PAGE 24 SHEP OSS OP SYS AND FMS 
—RP-ORT—-DEVIGE-HANDLER: 
634 BE94 A4S7TA LDY PDHICD 3 GET IOCB DISPL 
635 -BB96 A2FC +Bx EFC +— AND XK -VALVE FBR -4-BYTES 
636 BE98 B53A PDHM2 LDA $3A, X 3 GET APPLE SWITCH VALUE 
637 B&9A FFOBBD STA ICAUX2, Y + PUT INTO IOCB 
—_——438B89D-68 PLA +—-RESTORE—-SHIFCH- ——_—- 
639 BSIE 953A STA $3A, X i FROM STACK 
640 BBAO 88 DEY 
—641—-BBAL ES SENS — = 
642 BBA2 DOF4 BNE PDHM2 s BR IF MORE TO MOVE 
643 3 
+44 BBA4 FOIF _ BEG AEDSTA +—BONE - s 
645 i 
646 BBAS& PDHGO EQu * 
647 B8A6 A578 ——-—--———-. --—-L DA PF BHF LG ——____5-_ 000 eR 
648 BBAS FOO3 BEQ@ PDHBO i BR 
649 BBAA 6C3800 vMP ($38) 
£50 ——__—_—_——— + = 
651 BBAD A57C PDHBO LDA PDHCHR i LOAD DATA 
652 BEAF 4980 PDHOSW EOR #$80 3 INVERT MSB 
—_—_—+53-BS8B 14632600 SMP. £36} +— OUTPUT CHAR es 


654 


PAGE 


25 SHEP OSS OP SYS AN 


ID FMS 


APPLE EDITOR DEVICE HANDLER —— 
PAGE ‘APPLE EDITOR DEVICE HANDLER’ 
655 as ae oar ee aie Se tres 
656 ; AEDDH — APPLE EDITOR DEVICE HANDLER 
657 3 
— 658 AEDDH —- ——- — — — - 
659 BBB4 COBS DB @@AEDOPN i OPEN 
660 BSBSé C5BE DB @@AEDSTA + STATUS 
—_—__661_B8BS-CCBS —— - DB -@@AEDCBT—_—__-_-_—+--CET BYTE —___—— 
662 BSBA F4E8 DB @@AEDPBT i; PUT BYTE 
663 BEBC C5EBS DB @@AEDSTA i; CLOSE 
_ 664 BSBECSBS —_________-__DB -_____@G@AEDSTA +—DEVICE DEPENDENT—-VECTOR 
665 3 
666 AEDOPN 
67 BECO A900 —-— -- DA #0 -- -— + SET -QUFLAG=0 
668 B8C2 SDFABS STA AEDFLG 
669 i 
—-£70 ——- AEDINT — — ae 
671 AEDSTA 
672 BEC5 A001 LDY #ICSOK 3+ SET OK STATUS 
673 JAE RTN — — Ses as 
674 BBC7 AS57C LDA AEDCHAR i; GET DATA CHAR 
675 BEC? 4980 EGR #$80 i INVERT MSB 
476 -- — AEDDDC 
677 BBCB 60 RTS i+ AND RETURN 
678 ; 
—679 .-_______—_—_— -AEDGBT —— _ 
680 BSCC ACFABS LDY AEDFLG + GET FLAG/COUNT 
681 BECF DO1O BNE !AEDG1 +BR NOT ZERO 
482 . + a - - - 
683 BBD1 A98D LDA #$8D - 
684 B8D3 8533 STA $33 
—685 BEDS A200 .--— -- —— 4 Dx —#O —— = 
686 BBD7 2075FD JSR $FD75 3 GET A LINE 
687 B8DA E8 INX is INC BY 1 
_ 688 BBDB -SEFBBS ——____—____8TX ———_AEDCNT —_-- +, BAVE -LINE -S1ZE — --—— 
689 BBDE ACFABS LDY AEDFLG +GET ZERO COUNT 
690 i 
71 4AEDGI Fe saeEEy 
692 BBE1 B90002 LDA $200, Y i+ GET DATA CHAR 
693 BBE4 857C STA AEDCHAR i+ SAVE CHAR 
694 BS8E6 C8. ————______-InY¥ -——_—___--- -—___-—_—_ + ¢ -F9 -NEXT}——_____- 
695 BEE7 CCFBBS CPY AEDCNT 3; XFR ALL CHARS YET 
696 BBEA 9002 BCC !AEDG2 i+ BR IF NOT 
—_——97. —__-—- DY ——-- 6 ————— —+ SET FLAG=9-—_—__—____-— 
698 3 
699 BEEE SCFABE 'AEDG2 STY AEDFLG + SET NEW COUNT/FLAG 
200 BRFI4CCSBS SMP —AEDSTA +CO-GET-STATUS -& RETURN —- 
701 j 
702 BeF4 AEDPBT EQU * 
703 BSFA2OAFBS —JER - PDHOSH 4+—BUFPUT—GHAR a a 
( 704 BEF7 4CCSBS8 JMP AEDSTA 360 END STATUS 
705 3 
on FOS © BSFA AEDFLS —RMB ——__1-___—______—__,_ EDI For #L AG ——_-—_ 
707 BeFB AEDCNT RMB 1 + EDITOR COUNT 


708 


OPTIMIZED SYSTEMS SOFTWARE 


DISK FILE MANAGER 


for the Apple II (R) 


Feb 1980 


Version 1.0 


OSS Disk File Manager is Copyright (c) 1980 
Shepardson Microsystems, Ink. 


Optimized Systems Software 
Shepardson Microsystems, Inc 

20823 Stevens Creek Blvd, Bldg C4-H 
Cupertino, CA 95014 

Telephone: 408-257-9900 


Apple II and Disk 11 are registered trademarks of Apple Computer, Inc 


TABLE OF CONTENTS 


INTRODUCTION . 26 ose 
Drive A: and B: 
Disk Organization 


FILE NAMES 
Primary and Extension Names 
Wild Card Search Charactrers 


FILE MANAGER FUNCTION 


FUNCTION DETAILS 
Open Output 
Open Input . 
Open Update 
Open Directory 
Close 
Getbyte 
Putbyte 
Note . 

Point 
Erase 
Protect 
Unprotect 
Rename 
Status 


RETURN CODES 


DISK I/0 
DIOB DETAILS 


DFM BUFFERS 


i 


CO VWVOMDONNNNGOCA SHE W NV 


_ 


11 


11 


12 


INTRODUCTION 


The OSS DISK FILE MANAGER runs under the OSS operating system as a 
Device Handler. The DFM has two entries in the Device Table. The 
"A:" device is for files located on disk 1 in slot 6 The "B:" 
device is for files on disk 2 in slot 6 All file manager functions 
are accessed through the operating system via the IOCBs 


An OSS disk is organized to contain 719 (or 680 if a boot is included) 
128 bytes sectors numbered O through 719. The file manager reserves 
9 sectors for the file management functions. Eight of the reserved 
sectors are the file directory. Each file directory sector can 
contain eight file entries; thus, an OSS disk may contain a maximum 

of 64 files 


FILE NAMES 


The DFM accesses files in the file directory via an eleven character 
file name which the user specifies in the filename portion of the 
Operating System filespec. A DFM filename as received in the filespec 
has the general form 


primary—name. extension-name 


The primary file name must start with an aplha character (A-Z) and 
may contain up to seven following aplhanumeric (A-Z,0-9) characters 
The extension filename may contain from zero to three aplhanumeric 
characters. The DFM will pad the primary name to eight characters 
with blanks. The extension name will be padded to three charecters 
with blanks 


The DFM filename received in the filespec may also contain the 
“wild card” search characters "#*" and "?". The "7" is interpeted 
as "any character" in the directory search-for-match operation 

A file name of eleven "?" would match with any and all file names 
during a directory search. The “*" wild card is used to cause a 
file name to be padded with "?" characters rather than blank 
Characters. The file name "*.*" is a substitute for a file name of 
eleven "7" characters 


FILE MANAGER FUNCTIONS 


The file manager performs the following file management functions 


Open Output Open a file (new or old) for output 
at the start of the file. 

Open Append Open a file (old) for output at the 
end of the file 

Open Update Open a file (old) for modification 
of existing records 

Open Directory Open the directory for output of 
ASCII formatted file information 

Close Close and open file 

Get Byte Get next sequential byte from file 


open for input, update, or directory 


Put Byte Put next sequential byte to a file 
opened for output, append or update 


Note For purpose of random access, obtain 
the disk address of the next byte to 
be used for GET or PUT 


Point Set the disk address of the next byte 
to GET or PUT. The file must be open 
for update to do Point 

Erase Erase a file or files 


Protect Protect a file or files from modification 
or erasure 


Unprotect Unprotect a protected file 
Rename Rename a file or files 
Status Obtain the status of a file 


All file manager functions are performed through OS using the system 
IOCBs (see OS manual). Various applications such as CP/A, BASIC 

and EASMD provide various levels of automatic access to file management 
functions 


FUNCTION DETAILS 
OPEN OUTPUT 


IO0CB COMMAND 1 
IOCB AUX1 8 
IOCB BUFADR Address of filespec 


The indicated file is open for output from the relative byte zero 
of the file. If the file already exists and is not protected, the 
existing file will be ERASEd before opening the named file as a 
new file. If the file does not exist, it will be created. Wild 
card characters are used to find the first and only the first match 
when searching for an existing file. If wild card characters are 
used and an existing file was not found, the wild card character 
will be changed to blanks. If an existing file is found, the new 
file name will be the old file name. A file OPENed for output 
will not appear in the directory until it has been CLOSEd. If an 
output file is not properly CLOSEd, some or all of the sectors 
that were acquired for it may be lost to the system 


OPEN INPUT 
IOCB COMMAND 1 
IOCB AUX1 4 
IOCB BUFADR Address of filespec 
The indic d file is OPENed for input. Any wild card characters are 


used to search for the first, and only the first match. If the file 
is not found, a "FILE NOT FOUND" error will be returned, and no file 
will be OPENed. \ 


OPEN APPEND 


I0CB COMMAND 1 
IOCB AUX1 5 
IOCB BUFADR Address of filespec 


The indicated file is OPENed for APPENDing data to the end of the file if 
the file is not protected. The rules for the file name search are the 
same as for INPUT. The file must exist. If a file OPENed for APPEND 

is not properly CLOSEd, the APPENDed data will be lost and the existing 
file will be unmodified. Non-closure of files OPENed for APPEND may 
cause some of all of the sectors containing the APPENDed data to be 

lost to the system 


OPEN UPDATE 
I0CB COMMAND 1 
IOCB AUX1 12 ($0C) 
IO0CB BUFADR Address of filespec 


The indicated file will be OPENed for UPDATE modifications provided it 


=i 


is not protected. The rules for directory searching are the same as for 
INPUT. The file must exist. The file 1/0 pointer is set for the first 


file data byte. GET and PUT functions are both 
may be intermixed as desired. If a file OPENed 
properly CLOSEd, a sectors worth of updates may 
opened for update cannot be extended beyonf its 


valid for UPDATE and 
for UPDATE is not 

be lost. A file 
end-of-file 


OPEN DIRECTORY 


IOCB COMMAND 1 
IOCB AUX1 6 
IOCB BUFADR Address of filespec 


The directory is OPENed for input to the caller via GETBYTE. The DFM 
will format each matched file name into an ASCII line suitable for 
printing or other processing. The line format is as follows 


CHARACTERS 

° Protect code, "#*" if protected else blank 
1 Blank 

2-9 Primary file name 

10 - 12 Extension filename 

13 Blank 

14 - 16 Count of sectors used by the file 

17 Carriage return (0D) 


The last line will contain the number of free sectors available in 
characters O through 2, followed by "FREE SECTORS” and a carriage 
return. An attempt to get data bytes beyond the last line’s carriage 
return will result in the end-of-file error 


The wild card characters are used in searching the directory. All 
file name matches that are found will be formatted and returned. If 


no matches are found, only the free sectors line will be returned 
The filespec "*. *" will return all file entries 


CLOSE 


I0CB COMMAND 12 (#0C) 


The indicated OPEN file is CLOSEd. 


GETBYTE 


IGCB DATA - see OS documentation 


The next sequential data byte is returned (usually to OS) in the A 
Tegister. The OS provides for data buffering. If an attempt is made 
to read beyond the end-of-file, the “END-OF-FILE” error will be 
returned. If the byte read is the last byte before the end-of-file, 
the end-of-file look ahead condition code will be returned 


PUTBYTE 


IOCB information - See OS manual 


The data in the (usually OS supplied) A-register will be put in the next 
sequential file location. If an attempt is made to write beyond the 
end-of-file in an UPDATE operation, the "END-OF-FILE" error will be 
returned 


NOTE 
1O0CB COMMAND 38 ($26) 
IOCB AUX3 Sector number (low) 
IOCB AUX4 Sector number (high) 
IOCB AUX5 Sector byte displacement (zero relative) 


Obtain the disk address of the NEXT sequential byte to be accessed 
The NOTE and POINT commands are used to build user directories for 
Tandom or direct access operations 


POINT ; 
IOCB COMMAND 37 ($25) 
IOCB AUX3 Sector number (low) 
IOCB AUX4 Sector number (high) 
IOCB AUX5 Sector byte displacement 


Set the disk address of the NEXT byte to be accessed. The file must 
be OPENed for UPDATE. If the indicated sector does not belong to the 
file that is OPENed, then an error will be returned. If the sector 
byte displacement is greater than that sectors current data length 
then an error will be returned 


ERASE 


IO0CB COMMAND 33 ($21) 
I0CB BUFADR Address of filespec 


The indicated file or files will be ERASEd unless they are protected 


The wild card characters are used to find all matching entries in the 
directory. Warning: the filespec #.* will ERASE ALL unprotected files 


PROTECT 


IOCB COMMAND 35 ($23) 
IO0CB BUFADR Address of filespec 


The indicated file or files will be protected against change and/or 
ERASure. The file name search is the same as for ERASE. 


UNPROTECT 


IOCB COMMAND 36 ($24) 
I0CB BUFADR Address of filespec 


The indicated file or files will be UNPROTECTed. The file name search 
is the same as for ERASE 


RENAME 


I0CB COMMAND 32 ($20) 
I0CB BUFPTR Address of filespec 


The indicated file or files will be RENAMEd. The filespec contains 

the name of the files to be searched for under the same rules as ERASE 
Following the search argument filespec is the new filename. The two 
filespecs must be separated by at least one non alphanumeric (A-Z, 0-9) 
(and non "*" or "?") characters. The new filename must not contain the 
device name "X:" part of a filespec. The new filename may contain wild 
card characters. Any wild card character in the new filename will be 
replaced by the corresponding character in the old filename. A file that 
is PROTECTed will not be RENAMEd. 


STATUS 


IOCB COMMAD 13 ($0D) 
IOCB BUFPTR Address of filespec 


The STATUS of the indicated file is returned. The wild card characters 
are used in the directory search. The first file found, and only the 
first file found will be STATUSed. The STATUS will indicate if 

the file exists and, if it does, whether it is PROTECTed or not. The 
$01 (normal) status indicates the file exists, for other status 

values see Return Code section 


RETURN CODES 


The following codes are returned by the File Managerin the IOCB status 
byte and in the Y register 


CODE MEANING 

$01 Normal operation ending 

$03 End-of-file look ahead. The byte just 
returned is the last byte in file 

$81 (129) No disk in drive, or device error 

$83 (131) Data I/O error 

$87 (135) Disk write protected 

SAL (161) All sectors buffers in use 

$A2 (162) Disk full. No free sectors 

$AB (163) 1/0 error reading system sector 
(directory or bit map) 

$A4 (164) Attempted to read a sector that was 
not part of currently OPENed file 

$A5 (165) Invalid file name 

SAG (166) Point information in error 

$A7 (167) File protected.\ 

$AB (168) Invalid DFM command 

$Ao (169) Directory full. Contains 64 files 

BAA (170) File not found in directory 

$AB (171) Point command issued when file was 


not OPEN for UPDATE 
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DISK 1/0 


The OSS disk that has been formatted without a boot record contains 
720 sectors of 128 bytes each. The sectors are numbered O through 
719 (decimal). The routine, DIOENT ($ABOO), performs the actual 
reading and writing of the sectors using the Disk I/O Block (DIOB) 
at $BD80. The DIOENT routine is normally used only by the DFM 
however, it is easily accessed by user programs. The reading or 
writing of disk sectors requires only that the correct information 
be placed in the DIOB and @ subroutine call made to DIOENT 


DIOB DETAILS 
LOCATION FIELD USAGE 


$BD80 DRIVE Disk drive to use 
1 = Slot 6 Drive 1 (A:) 
2 = Slot 6 Drive 2 (B:) 


$BD81 COMMAND Command function 
1 = Read sector 
2 = Write sector 


$BD82 STATUS I/O Status. 
$01 = Normal 
$81 = Device Error 


$83 = Data Error 
$84 = Invalid Command 
$87 = Write Protect 
$BD83 BUFFER Address of 128 byte buffer 
ADDRESS for data 1/0. (Low, High order) 
\ 
$BD85 SECTOR Absolute Sector Number 
NUMBER (O-$2CF). (Low, High order) 
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DFM BUFFERS 


The Disk File Manager requires 256 bytes of system buffer space plus 

one 128 byte buffer for each concurrently opened file. The system as 
delivered provides for a 768 byte buffer space at $AB00 (to $ABOO) 

The 768 bytes will provide for four (4) concurrently opened files 

The user may change both the address space used for the buffers and 

the number of sector buffers used. Location SADA2 (DFMBUF in OS system 
memory map) contains the start address of the buffer space. Location 
$SADA1 (DFMDIR) contains an allocation direction switch. If the direction 
Switch is $60, the buffer space will be allocated from the start address 
toward location $0000. If the direction switch is $00, the buffer space 
will be allocated from the start address toward location $FFFF. Location 
$ADAO (DFMNUMF) contains the number of sector buffers to allocate. The 
Space required for an allocation is (256 + number buffers * 128) 


Most OSS system programs are designed to end at location $A800 if 
the number of buffers is increased beyond the four provided for, the 
buffer space should be moved ($800 up is suggested). If less than 4 
buffers are required, the space from A800 to $A980 may be reclaimed 
for user application ram (in 128 byte chunks) 


The buffer space parameters may be permanently changed if INIT is 
used to re-write the boot 
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